home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / python / pythnlbn.lha / python-lib.info-4 (.txt) < prev    next >
GNU Info File  |  1993-07-29  |  50KB  |  964 lines
  1. This is Info file python-lib.info, produced by Makeinfo-1.43 from the
  2. input file @out.texi.
  3. This file describes the built-in types, exceptions and functions and
  4. the standard modules that come with the Python system.  It assumes
  5. basic knowledge about the Python language.  For an informal
  6. introduction to the language, see the Python Tutorial.  The Python
  7. Reference Manual gives a more formal definition of the language. 
  8. (These manuals are not yet available in INFO or Texinfo format.)
  9. Copyright (C) 1991, 1992, 1993 by Stichting Mathematisch Centrum,
  10. Amsterdam, The Netherlands.
  11. All Rights Reserved
  12. Permission to use, copy, modify, and distribute this software and its
  13. documentation for any purpose and without fee is hereby granted,
  14. provided that the above copyright notice appear in all copies and that
  15. both that copyright notice and this permission notice appear in
  16. supporting documentation, and that the names of Stichting Mathematisch
  17. Centrum or CWI not be used in advertising or publicity pertaining to
  18. distribution of the software without specific, written prior
  19. permission.
  20. STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
  21. THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  22. FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
  23. FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  24. WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  25. ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
  26. OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  27. File: python-lib.info,  Node: SGI MACHINES ONLY,  Next: SUN SPARC MACHINES ONLY,  Prev: STDWIN ONLY,  Up: Top
  28. SGI MACHINES ONLY
  29. *****************
  30. * Menu:
  31. * al::                          Built-in Module `al'
  32. * AL (uppercase)::              Standard Module `AL'
  33. * audio::                       Built-in Module `audio'
  34. * gl::                          Built-in Module `gl'
  35. * fm::                          Built-in Module `fm'
  36. * Standard Modules GL and DEVICE::  Standard Modules `GL' and `DEVICE'
  37. * fl::                          Built-in Module `fl'
  38. * FL (uppercase)::              Standard Module `FL'
  39. * flp::                         Standard Module `flp'
  40. * panel::                       Standard Module `panel'
  41. * panelparser::                 Standard Module `panelparser'
  42. * pnl::                         Built-in Module `pnl'
  43. * jpeg::                        Built-in Module `jpeg'
  44. * imgfile::                     Built-in module `imgfile'
  45. * imageop::                     Built-in module `imageop'
  46. File: python-lib.info,  Node: al,  Next: AL (uppercase),  Up: SGI MACHINES ONLY
  47. Built-in Module `al'
  48. ====================
  49. This module provides access to the audio facilities of the Indigo and
  50. 4D/35 workstations, described in section 3A of the IRIX 4.0 man pages
  51. (and also available as an option in IRIX 3.3).  You'll need to read
  52. those man pages to understand what these functions do!  Some of the
  53. functions are not available in releases below 4.0.5.  Again, see the
  54. manual to check whether a specific function is available on your
  55. platform.
  56. Symbolic constants from the C header file `<audio.h>' are defined in
  57. the standard module `AL', see below.
  58. *Warning:* the current version of the audio library may dump core when
  59. bad argument values are passed rather than returning an error status. 
  60. Unfortunately, since the precise circumstances under which this may
  61. happen are undocumented and hard to check, the Python interface can
  62. provide no protection against this kind of problems.  (One example is
  63. specifying an excessive queue size -- there is no documented upper
  64. limit.)
  65. Module `al' defines the following functions:
  66.  -- function of module al: openport (NAME, DIRECTION, CONFIG)
  67.      Equivalent to the C function ALopenport().  The name and direction
  68.      arguments are strings.  The optional config argument is an opaque
  69.      configuration object as returned by `al.newconfig()'.  The return
  70.      value is an opaque port object; methods of port objects are
  71.      described below.
  72.  -- function of module al: newconfig ()
  73.      Equivalent to the C function ALnewconfig().  The return value is
  74.      a new opaque configuration object; methods of configuration
  75.      objects are described below.
  76.  -- function of module al: queryparams (DEVICE)
  77.      Equivalent to the C function ALqueryparams().  The device
  78.      argument is an integer.  The return value is a list of integers
  79.      containing the data returned by ALqueryparams().
  80.  -- function of module al: getparams (DEVICE, LIST)
  81.      Equivalent to the C function ALgetparams().  The device argument
  82.      is an integer.  The list argument is a list such as returned by
  83.      `queryparams'; it is modified in place (!).
  84.  -- function of module al: setparams (DEVICE, LIST)
  85.      Equivalent to the C function ALsetparams().  The device argument
  86.      is an integer.The list argument is a list such as returned by
  87.      `al.queryparams'.
  88. Configuration objects (returned by `al.newconfig()' have the following
  89. methods:
  90.  -- Method on audio configuration object: getqueuesize ()
  91.      Return the queue size; equivalent to the C function
  92.      ALgetqueuesize().
  93.  -- Method on audio configuration object: setqueuesize (SIZE)
  94.      Set the queue size; equivalent to the C function ALsetqueuesize().
  95.  -- Method on audio configuration object: getwidth ()
  96.      Get the sample width; equivalent to the C function ALgetwidth().
  97.  -- Method on audio configuration object: getwidth (WIDTH)
  98.      Set the sample width; equivalent to the C function ALsetwidth().
  99.  -- Method on audio configuration object: getchannels ()
  100.      Get the channel count; equivalent to the C function
  101.      ALgetchannels().
  102.  -- Method on audio configuration object: setchannels (NCHANNELS)
  103.      Set the channel count; equivalent to the C function
  104.      ALsetchannels().
  105.  -- Method on audio configuration object: getsampfmt ()
  106.      Get the sample format; equivalent to the C function
  107.      ALgetsampfmt().
  108.  -- Method on audio configuration object: setsampfmt (SAMPFMT)
  109.      Set the sample format; equivalent to the C function
  110.      ALsetsampfmt().
  111.  -- Method on audio configuration object: getfloatmax ()
  112.      Get the maximum value for floating sample formats; equivalent to
  113.      the C function ALgetfloatmax().
  114.  -- Method on audio configuration object: setfloatmax (FLOATMAX)
  115.      Set the maximum value for floating sample formats; equivalent to
  116.      the C function ALsetfloatmax().
  117. Port objects (returned by `al.openport()' have the following methods:
  118.  -- Method on audio port object: closeport ()
  119.      Close the port; equivalent to the C function ALcloseport().
  120.  -- Method on audio port object: getfd ()
  121.      Return the file descriptor as an int; equivalent to the C function
  122.      ALgetfd().
  123.  -- Method on audio port object: getfilled ()
  124.      Return the number of filled samples; equivalent to the C function
  125.      ALgetfilled().
  126.  -- Method on audio port object: getfillable ()
  127.      Return the number of fillable samples; equivalent to the C
  128.      function ALgetfillable().
  129.  -- Method on audio port object: readsamps (NSAMPLES)
  130.      Read a number of samples from the queue, blocking if necessary;
  131.      equivalent to the C function ALreadsamples.  The data is returned
  132.      as a string containing the raw data (e.g. 2 bytes per sample in
  133.      big-endian byte order (high byte, low byte) if you have set the
  134.      sample width to 2 bytes.
  135.  -- Method on audio port object: writesamps (SAMPLES)
  136.      Write samples into the queue, blocking if necessary; equivalent
  137.      to the C function ALwritesamples.  The samples are encoded as
  138.      described for the `readsamps' return value.
  139.  -- Method on audio port object: getfillpoint ()
  140.      Return the `fill point'; equivalent to the C function
  141.      ALgetfillpoint().
  142.  -- Method on audio port object: setfillpoint (FILLPOINT)
  143.      Set the `fill point'; equivalent to the C function
  144.      ALsetfillpoint().
  145.  -- Method on audio port object: getconfig ()
  146.      Return a configuration object containing the current
  147.      configuration of the port; equivalent to the C function
  148.      ALgetconfig().
  149.  -- Method on audio port object: setconfig (CONFIG)
  150.      Set the configuration from the argument, a configuration object;
  151.      equivalent to the C function ALsetconfig().
  152.  -- Method on audio port object: getstatus (LIST)
  153.      Get status information on last error equivalent to C function
  154.      ALgetstatus().
  155. File: python-lib.info,  Node: AL (uppercase),  Next: audio,  Prev: al,  Up: SGI MACHINES ONLY
  156. Standard Module `AL'
  157. ====================
  158. This module defines symbolic constants needed to use the built-in
  159. module `al' (see above); they are equivalent to those defined in the C
  160. header file `<audio.h>' except that the name prefix `AL_' is omitted. 
  161. Read the module source for a complete list of the defined names. 
  162. Suggested use:
  163.      import al
  164.      from AL import *
  165. File: python-lib.info,  Node: audio,  Next: gl,  Prev: AL (uppercase),  Up: SGI MACHINES ONLY
  166. Built-in Module `audio'
  167. =======================
  168. *Note:* This module is obsolete, since the hardware to which it
  169. interfaces is obsolete.  For audio on the Indigo or 4D/35, see
  170. built-in module `al' above.
  171. This module provides rudimentary access to the audio I/O device
  172. `/dev/audio' on the Silicon Graphics Personal IRIS 4D/25; see
  173. audio(7). It supports the following operations:
  174.  -- function of module audio: setoutgain (N)
  175.      Sets the output gain.  `0 <= N < 256'.
  176.  -- function of module audio: getoutgain ()
  177.      Returns the output gain.
  178.  -- function of module audio: setrate (N)
  179.      Sets the sampling rate: `1' = 32K/sec, `2' = 16K/sec, `3' =
  180.      8K/sec.
  181.  -- function of module audio: setduration (N)
  182.      Sets the `sound duration' in units of 1/100 seconds.
  183.  -- function of module audio: read (N)
  184.      Reads a chunk of N sampled bytes from the audio input (line in or
  185.      microphone).  The chunk is returned as a string of length n. 
  186.      Each byte encodes one sample as a signed 8-bit quantity using
  187.      linear encoding.  This string can be converted to numbers using
  188.      `chr2num()' described below.
  189.  -- function of module audio: write (BUF)
  190.      Writes a chunk of samples to the audio output (speaker).
  191. These operations support asynchronous audio I/O:
  192.  -- function of module audio: start_recording (N)
  193.      Starts a second thread (a process with shared memory) that begins
  194.      reading N bytes from the audio device.  The main thread
  195.      immediately continues.
  196.  -- function of module audio: wait_recording ()
  197.      Waits for the second thread to finish and returns the data read.
  198.  -- function of module audio: stop_recording ()
  199.      Makes the second thread stop reading as soon as possible. 
  200.      Returns the data read so far.
  201.  -- function of module audio: poll_recording ()
  202.      Returns true if the second thread has finished reading (so
  203.      `wait_recording()' would return the data without delay).
  204.  -- function of module audio: start_playing ()
  205.  -- function of module audio: wait_playing ()
  206.  -- function of module audio: stop_playing ()
  207.  -- function of module audio: poll_playing ()
  208.      Similar but for output.  `stop_playing()' returns a lower bound
  209.      for the number of bytes actually played (not very accurate).
  210. The following operations do not affect the audio device but are
  211. implemented in C for efficiency:
  212.  -- function of module audio: amplify (BUF, F1, F2)
  213.      Amplifies a chunk of samples by a variable factor changing from
  214.      `F1/256' to `F2/256.' Negative factors are allowed.  Resulting
  215.      values that are to large to fit in a byte are clipped.
  216.  -- function of module audio: reverse (BUF)
  217.      Returns a chunk of samples backwards.
  218.  -- function of module audio: add (BUF1, BUF2)
  219.      Bytewise adds two chunks of samples.  Bytes that exceed the range
  220.      are clipped.  If one buffer is shorter, it is assumed to be
  221.      padded with zeros.
  222.  -- function of module audio: chr2num (BUF)
  223.      Converts a string of sampled bytes as returned by `read()' into a
  224.      list containing the numeric values of the samples.
  225.  -- function of module audio: num2chr (LIST)
  226.      Converts a list as returned by `chr2num()' back to a buffer
  227.      acceptable by `write()'.
  228. File: python-lib.info,  Node: gl,  Next: fm,  Prev: audio,  Up: SGI MACHINES ONLY
  229. Built-in Module `gl'
  230. ====================
  231. This module provides access to the Silicon Graphics *Graphics Library*. 
  232. It is available only on Silicon Graphics machines.
  233. *Warning:* Some illegal calls to the GL library cause the Python
  234. interpreter to dump core.  In particular, the use of most GL calls is
  235. unsafe before the first window is opened.
  236. The module is too large to document here in its entirety, but the
  237. following should help you to get started.  The parameter conventions
  238. for the C functions are translated to Python as follows:
  239.    * All (short, long, unsigned) int values are represented by Python
  240.      integers.
  241.    * All float and double values are represented by Python floating
  242.      point numbers.  In most cases, Python integers are also allowed.
  243.    * All arrays are represented by one-dimensional Python lists.  In
  244.      most cases, tuples are also allowed.
  245.    * All string and character arguments are represented by Python
  246.      strings, for instance, `winopen('Hi There!')' and `rotate(900,
  247.      'z')'.
  248.    * All (short, long, unsigned) integer arguments or return values
  249.      that are only used to specify the length of an array argument are
  250.      omitted.  For example, the C call
  251.           lmdef(deftype, index, np, props)
  252.      is translated to Python as
  253.           lmdef(deftype, index, props)
  254.    * Output arguments are omitted from the argument list; they are
  255.      transmitted as function return values instead.  If more than one
  256.      value must be returned, the return value is a tuple.  If the C
  257.      function has both a regular return value (that is not omitted
  258.      because of the previous rule) and an output argument, the return
  259.      value comes first in the tuple.  Examples: the C call
  260.           getmcolor(i, &red, &green, &blue)
  261.      is translated to Python as
  262.           red, green, blue = getmcolor(i)
  263. The following functions are non-standard or have special argument
  264. conventions:
  265.  -- function of module gl: varray (ARGUMENT)
  266.      Equivalent to but faster than a number of `v3d()' calls.  The
  267.      ARGUMENT is a list (or tuple) of points.  Each point must be a
  268.      tuple of coordinates `(X, Y, Z)' or `(X, Y)'.  The points may be
  269.      2- or 3-dimensional but must all have the same dimension.  Float
  270.      and int values may be mixed however.  The points are always
  271.      converted to 3D double precision points by assuming `Z = 0.0' if
  272.      necessary (as indicated in the man page), and for each point
  273.      `v3d()' is called.
  274.  -- function of module gl: nvarray ()
  275.      Equivalent to but faster than a number of `n3f' and `v3f' calls. 
  276.      The argument is an array (list or tuple) of pairs of normals and
  277.      points.  Each pair is a tuple of a point and a normal for that
  278.      point.  Each point or normal must be a tuple of coordinates `(X,
  279.      Y, Z)'.  Three coordinates must be given.  Float and int values
  280.      may be mixed.  For each pair, `n3f()' is called for the normal,
  281.      and then `v3f()' is called for the point.
  282.  -- function of module gl: vnarray ()
  283.      Similar to `nvarray()' but the pairs have the point first and the
  284.      normal second.
  285.  -- function of module gl: nurbssurface (S_K, T_K, CTL, S_ORD, T_ORD,
  286.           TYPE)
  287.      Defines a nurbs surface.  The dimensions of `CTL[][]' are
  288.      computed as follows: `[len(S_K) - S_ORD]', `[len(T_K) - T_ORD]'.
  289.  -- function of module gl: nurbscurve (KNOTS, CTLPOINTS, ORDER, TYPE)
  290.      Defines a nurbs curve.  The length of ctlpoints is `len(KNOTS) -
  291.      ORDER'.
  292.  -- function of module gl: pwlcurve (POINTS, TYPE)
  293.      Defines a piecewise-linear curve.  POINTS is a list of points. 
  294.      TYPE must be `N_ST'.
  295.  -- function of module gl: pick (N)
  296.  -- function of module gl: select (N)
  297.      The only argument to these functions specifies the desired size
  298.      of the pick or select buffer.
  299.  -- function of module gl: endpick ()
  300.  -- function of module gl: endselect ()
  301.      These functions have no arguments.  They return a list of
  302.      integers representing the used part of the pick/select buffer. 
  303.      No method is provided to detect buffer overrun.
  304. Here is a tiny but complete example GL program in Python:
  305.      import gl, GL, time
  306.      
  307.      def main():
  308.          gl.foreground()
  309.          gl.prefposition(500, 900, 500, 900)
  310.          w = gl.winopen('CrissCross')
  311.          gl.ortho2(0.0, 400.0, 0.0, 400.0)
  312.          gl.color(GL.WHITE)
  313.          gl.clear()
  314.          gl.color(GL.RED)
  315.          gl.bgnline()
  316.          gl.v2f(0.0, 0.0)
  317.          gl.v2f(400.0, 400.0)
  318.          gl.endline()
  319.          gl.bgnline()
  320.          gl.v2f(400.0, 0.0)
  321.          gl.v2f(0.0, 400.0)
  322.          gl.endline()
  323.          time.sleep(5)
  324.      
  325.      main()
  326. File: python-lib.info,  Node: fm,  Next: Standard Modules GL and DEVICE,  Prev: gl,  Up: SGI MACHINES ONLY
  327. Built-in Module `fm'
  328. ====================
  329. This module provides access to the IRIS *Font Manager* library.  It is
  330. available only on Silicon Graphics machines.  See also: 4Sight User's
  331. Guide, Section 1, Chapter 5: Using the IRIS Font Manager.
  332. This is not yet a full interface to the IRIS Font Manager.  Among the
  333. unsupported features are: matrix operations; cache operations;
  334. character operations (use string operations instead); some details of
  335. font info; individual glyph metrics; and printer matching.
  336. It supports the following operations:
  337.  -- function of module fm: init ()
  338.      Initialization function.  Calls `fminit()'.  It is normally not
  339.      necessary to call this function, since it is called automatically
  340.      the first time the `fm' module is imported.
  341.  -- function of module fm: findfont (FONTNAME)
  342.      Return a font handle object.  Calls `fmfindfont(FONTNAME)'.
  343.  -- function of module fm: enumerate ()
  344.      Returns a list of available font names.  This is an interface to
  345.      `fmenumerate()'.
  346.  -- function of module fm: prstr (STRING)
  347.      Render a string using the current font (see the `setfont()' font
  348.      handle method below).  Calls `fmprstr(STRING)'.
  349.  -- function of module fm: setpath (STRING)
  350.      Sets the font search path.  Calls `fmsetpath(string)'.  (XXX Does
  351.      not work!?!)
  352.  -- function of module fm: fontpath ()
  353.      Returns the current font search path.
  354. Font handle objects support the following operations:
  355.  -- Method on font handle: scalefont (FACTOR)
  356.      Returns a handle for a scaled version of this font.  Calls
  357.      `fmscalefont(FH, FACTOR)'.
  358.  -- Method on font handle: setfont ()
  359.      Makes this font the current font.  Note: the effect is undone
  360.      silently when the font handle object is deleted.  Calls
  361.      `fmsetfont(FH)'.
  362.  -- Method on font handle: getfontname ()
  363.      Returns this font's name.  Calls `fmgetfontname(FH)'.
  364.  -- Method on font handle: getcomment ()
  365.      Returns the comment string associated with this font.  Raises an
  366.      exception if there is none.  Calls `fmgetcomment(FH)'.
  367.  -- Method on font handle: getfontinfo ()
  368.      Returns a tuple giving some pertinent data about this font.  This
  369.      is an interface to `fmgetfontinfo()'.  The returned tuple
  370.      contains the following numbers: `(PRINTERMATCHED, FIXED_WIDTH,
  371.      XORIG, YORIG, XSIZE, YSIZE, HEIGHT, NGLYPHS)'.
  372.  -- Method on font handle: getstrwidth (STRING)
  373.      Returns the width, in pixels, of the string when drawn in this
  374.      font.  Calls `fmgetstrwidth(FH, STRING)'.
  375. File: python-lib.info,  Node: Standard Modules GL and DEVICE,  Next: fl,  Prev: fm,  Up: SGI MACHINES ONLY
  376. Standard Modules `GL' and `DEVICE'
  377. ==================================
  378. These modules define the constants used by the Silicon Graphics
  379. *Graphics Library* that C programmers find in the header files
  380. `<gl/gl.h>' and `<gl/device.h>'.  Read the module source files for
  381. details.
  382. File: python-lib.info,  Node: fl,  Next: FL (uppercase),  Prev: Standard Modules GL and DEVICE,  Up: SGI MACHINES ONLY
  383. Built-in Module `fl'
  384. ====================
  385. This module provides an interface to the FORMS Library by Mark
  386. Overmars, version 2.0b.  For more info about FORMS, write to
  387. markov@cs.ruu.nl.
  388. Most functions are literal translations of their C equivalents,
  389. dropping the initial `fl_' from their name.  Constants used by the
  390. library are defined in module `FL' described below.
  391. The creation of objects is a little different in Python than in C:
  392. instead of the `current form' maintained by the library to which new
  393. FORMS objects are added, all functions that add a FORMS object to a
  394. button are methods of the Python object representing the form. 
  395. Consequently, there are no Python equivalents for the C functions
  396. `fl_addto_form' and `fl_end_form', and the equivalent of `fl_bgn_form'
  397. is called `fl.make_form'.
  398. Watch out for the somewhat confusing terminology: FORMS uses the word
  399. "object" for the buttons, sliders etc. that you can place in a form. 
  400. In Python, `object' means any value.  The Python interface to FORMS
  401. introduces two new Python object types: form objects (representing an
  402. entire form) and FORMS objects (representing one button, slider etc.). 
  403. Hopefully this isn't too confusing...
  404. There are no `free objects' in the Python interface to FORMS, nor is
  405. there an easy way to add object classes written in Python.  The FORMS
  406. interface to GL event handling is avaiable, though, so you can mix
  407. FORMS with pure GL windows.
  408. *Please note:* importing `fl' implies a call to the GL function
  409. `foreground()' and to the FORMS routine `fl_init()'.
  410. * Menu:
  411. * Functions defined in module fl::  Functions defined in module `fl'
  412. * Form object::                 Form object methods and data attributes
  413. * FORMS object::                FORMS object methods and data attributes
  414. File: python-lib.info,  Node: Functions defined in module fl,  Next: Form object,  Up: fl
  415. Functions defined in module `fl'
  416. --------------------------------
  417. Module `fl' defines the following functions.  For more information
  418. about what they do, see the description of the equivalent C function
  419. in the FORMS documentation:
  420.  -- function of module fl: make_form (TYPE, WIDTH, HEIGHT)
  421.      Create a form with given type, width and height.  This returns a
  422.      "form" object, whose methods are described below.
  423.  -- function of module fl: do_forms ()
  424.      The standard FORMS main loop.  Returns a Python object
  425.      representing the FORMS object needing interaction, or the special
  426.      value `FL.EVENT'.
  427.  -- function of module fl: check_forms ()
  428.      Check for FORMS events.  Returns what `do_forms' above returns,
  429.      or `None' if there is no event that immediately needs interaction.
  430.  -- function of module fl: set_event_call_back (FUNCTION)
  431.      Set the event callback function.
  432.  -- function of module fl: set_graphics_mode (RGBMODE, DOUBLEBUFFERING)
  433.      Set the graphics modes.
  434.  -- function of module fl: get_rgbmode ()
  435.      Return the current rgb mode.  This is the value of the C global
  436.      variable `fl_rgbmode'.
  437.  -- function of module fl: show_message (STR1, STR2, STR3)
  438.      Show a dialog box with a three-line message and an OK button.
  439.  -- function of module fl: show_question (STR1, STR2, STR3)
  440.      Show a dialog box with a three-line message and YES and NO
  441.      buttons.  It returns `1' if the user pressed YES, `0' if NO.
  442.  -- function of module fl: show_choice (STR1, STR2, STR3, BUT1, BUT2,
  443.           BUT3)
  444.      Show a dialog box with a three-line message and up to three
  445.      buttons.  It returns the number of the button clicked by the user
  446.      (`1', `2' or `3').  The BUT2 and BUT3 arguments are optional.
  447.  -- function of module fl: show_input (PROMPT, DEFAULT)
  448.      Show a dialog box with a one-line prompt message and text field in
  449.      which the user can enter a string.  The second argument is the
  450.      default input string.  It returns the string value as edited by
  451.      the user.
  452.  -- function of module fl: show_file_selector (MESSAGE, DIRECTORY,
  453.           PATTERN, DEFAULT)
  454.      Show a dialog box inm which the user can select a file.  It
  455.      returns the absolute filename selected by the user, or `None' if
  456.      the user presses Cancel.
  457.  -- function of module fl: get_directory ()
  458.  -- function of module fl: get_pattern ()
  459.  -- function of module fl: get_filename ()
  460.      These functions return the directory, pattern and filename (the
  461.      tail part only) selected by the user in the last
  462.      `show_file_selector' call.
  463.  -- function of module fl: qdevice (DEV)
  464.  -- function of module fl: unqdevice (DEV)
  465.  -- function of module fl: isqueued (DEV)
  466.  -- function of module fl: qtest ()
  467.  -- function of module fl: qread ()
  468.  -- function of module fl: qreset ()
  469.  -- function of module fl: qenter (DEV, VAL)
  470.  -- function of module fl: get_mouse ()
  471.  -- function of module fl: tie (BUTTON, VALUATOR1, VALUATOR2)
  472.      These functions are the FORMS interfaces to the corresponding GL
  473.      functions.  Use these if you want to handle some GL events
  474.      yourself when using `fl.do_events'.  When a GL event is detected
  475.      that FORMS cannot handle, `fl.do_forms()' returns the special
  476.      value `FL.EVENT' and you should call `fl.qread()' to read the
  477.      event from the queue.  Don't use the equivalent GL functions!
  478.  -- function of module fl: color ()
  479.  -- function of module fl: mapcolor ()
  480.  -- function of module fl: getmcolor ()
  481.      See the description in the FORMS documentation of `fl_color',
  482.      `fl_mapcolor' and `fl_getmcolor'.
  483. File: python-lib.info,  Node: Form object,  Next: FORMS object,  Prev: Functions defined in module fl,  Up: fl
  484. Form object methods and data attributes
  485. ---------------------------------------
  486. Form objects (returned by `fl.make_form()' above) have the following
  487. methods.  Each method corresponds to a C function whose name is
  488. prefixed with `fl_'; and whose first argument is a form pointer;
  489. please refer to the official FORMS documentation for descriptions.
  490. All the `add_...' functions return a Python object representing the
  491. FORMS object.  Methods of FORMS objects are described below.  Most
  492. kinds of FORMS object also have some methods specific to that kind;
  493. these methods are listed here.
  494.  -- Method on form object: show_form (PLACEMENT, BORDERTYPE, NAME)
  495.      Show the form.
  496.  -- Method on form object: hide_form ()
  497.      Hide the form.
  498.  -- Method on form object: redraw_form ()
  499.      Redraw the form.
  500.  -- Method on form object: set_form_position (X, Y)
  501.      Set the form's position.
  502.  -- Method on form object: freeze_form ()
  503.      Freeze the form.
  504.  -- Method on form object: unfreeze_form ()
  505.      Unfreeze the form.
  506.  -- Method on form object: activate_form ()
  507.      Activate the form.
  508.  -- Method on form object: deactivate_form ()
  509.      Deactivate the form.
  510.  -- Method on form object: bgn_group ()
  511.      Begin a new group of objects; return a group object.
  512.  -- Method on form object: end_group ()
  513.      End the current group of objects.
  514.  -- Method on form object: find_first ()
  515.      Find the first object in the form.
  516.  -- Method on form object: find_last ()
  517.      Find the last object in the form.
  518.  -- Method on form object: add_box (TYPE, X, Y, W, H, NAME)
  519.      Add a box object to the form.  No extra methods.
  520.  -- Method on form object: add_text (TYPE, X, Y, W, H, NAME)
  521.      Add a text object to the form.  No extra methods.
  522.  -- Method on form object: add_clock (TYPE, X, Y, W, H, NAME)
  523.      Add a clock object to the form. 
  524.       Method: `get_clock'.
  525.  -- Method on form object: add_button (TYPE, X, Y, W, H, NAME)
  526.      Add a button object to the form. 
  527.       Methods: `get_button', `set_button'.
  528.  -- Method on form object: add_lightbutton (TYPE, X, Y, W, H, NAME)
  529.      Add a lightbutton object to the form. 
  530.       Methods: `get_button', `set_button'.
  531.  -- Method on form object: add_roundbutton (TYPE, X, Y, W, H, NAME)
  532.      Add a roundbutton object to the form. 
  533.       Methods: `get_button', `set_button'.
  534.  -- Method on form object: add_slider (TYPE, X, Y, W, H, NAME)
  535.      Add a slider object to the form. 
  536.       Methods: `set_slider_value', `get_slider_value',
  537.      `set_slider_bounds', `get_slider_bounds', `set_slider_return',
  538.      `set_slider_size', `set_slider_precision', `set_slider_step'.
  539.  -- Method on form object: add_valslider (TYPE, X, Y, W, H, NAME)
  540.      Add a valslider object to the form. 
  541.       Methods: `set_slider_value', `get_slider_value',
  542.      `set_slider_bounds', `get_slider_bounds', `set_slider_return',
  543.      `set_slider_size', `set_slider_precision', `set_slider_step'.
  544.  -- Method on form object: add_dial (TYPE, X, Y, W, H, NAME)
  545.      Add a dial object to the form. 
  546.       Methods: `set_dial_value', `get_dial_value', `set_dial_bounds',
  547.      `get_dial_bounds'.
  548.  -- Method on form object: add_positioner (TYPE, X, Y, W, H, NAME)
  549.      Add a positioner object to the form. 
  550.       Methods: `set_positioner_xvalue', `set_positioner_yvalue',
  551.      `set_positioner_xbounds', `set_positioner_ybounds',
  552.      `get_positioner_xvalue', `get_positioner_yvalue',
  553.      `get_positioner_xbounds', `get_positioner_ybounds'.
  554.  -- Method on form object: add_counter (TYPE, X, Y, W, H, NAME)
  555.      Add a counter object to the form. 
  556.       Methods: `set_counter_value', `get_counter_value',
  557.      `set_counter_bounds', `set_counter_step', `set_counter_precision',
  558.      `set_counter_return'.
  559.  -- Method on form object: add_input (TYPE, X, Y, W, H, NAME)
  560.      Add a input object to the form. 
  561.       Methods: `set_input', `get_input', `set_input_color',
  562.      `set_input_return'.
  563.  -- Method on form object: add_menu (TYPE, X, Y, W, H, NAME)
  564.      Add a menu object to the form. 
  565.       Methods: `set_menu', `get_menu', `addto_menu'.
  566.  -- Method on form object: add_choice (TYPE, X, Y, W, H, NAME)
  567.      Add a choice object to the form. 
  568.       Methods: `set_choice', `get_choice', `clear_choice',
  569.      `addto_choice', `replace_choice', `delete_choice',
  570.      `get_choice_text', `set_choice_fontsize', `set_choice_fontstyle'.
  571.  -- Method on form object: add_browser (TYPE, X, Y, W, H, NAME)
  572.      Add a browser object to the form. 
  573.       Methods: `set_browser_topline', `clear_browser',
  574.      `add_browser_line', `addto_browser', `insert_browser_line',
  575.      `delete_browser_line', `replace_browser_line', `get_browser_line',
  576.      `load_browser', `get_browser_maxline', `select_browser_line',
  577.      `deselect_browser_line', `deselect_browser',
  578.      `isselected_browser_line', `get_browser', `set_browser_fontsize',
  579.      `set_browser_fontstyle', `set_browser_specialkey'.
  580.  -- Method on form object: add_timer (TYPE, X, Y, W, H, NAME)
  581.      Add a timer object to the form. 
  582.       Methods: `set_timer', `get_timer'.
  583. Form objects have the following data attributes; see the FORMS
  584. documentation:
  585. *Name*
  586.      *Type*  --  *Meaning*
  587. `window'
  588.      int (read-only)  --  GL window id
  589.      float  --  form width
  590.      float  --  form height
  591.      float  --  form x origin
  592.      float  --  form y origin
  593. `deactivated'
  594.      int  --  nonzero if form is deactivated
  595. `visible'
  596.      int  --  nonzero if form is visible
  597. `frozen'
  598.      int  --  nonzero if form is frozen
  599. `doublebuf'
  600.      int  --  nonzero if double buffering on
  601. File: python-lib.info,  Node: FORMS object,  Prev: Form object,  Up: fl
  602. FORMS object methods and data attributes
  603. ----------------------------------------
  604. Besides methods specific to particular kinds of FORMS objects, all
  605. FORMS objects also have the following methods:
  606.  -- Method on FORMS object: set_call_back (FUNCTION, ARGUMENT)
  607.      Set the object's callback function and argument.  When the object
  608.      needs interaction, the callback function will be called with two
  609.      arguments: the object, and the callback argument.  (FORMS objects
  610.      without a callback function are returned by `fl.do_forms()' or
  611.      `fl.check_forms()' when they need interaction.)  Call this method
  612.      without arguments to remove the callback function.
  613.  -- Method on FORMS object: delete_object ()
  614.      Delete the object.
  615.  -- Method on FORMS object: show_object ()
  616.      Show the object.
  617.  -- Method on FORMS object: hide_object ()
  618.      Hide the object.
  619.  -- Method on FORMS object: redraw_object ()
  620.      Redraw the object.
  621.  -- Method on FORMS object: freeze_object ()
  622.      Freeze the object.
  623.  -- Method on FORMS object: unfreeze_object ()
  624.      Unfreeze the object.
  625. FORMS objects have these data attributes; see the FORMS documentation:
  626. *Name*
  627.      *Type*  --  *Meaning*
  628. `objclass'
  629.      int (read-only)  --  object class
  630. `type'
  631.      int (read-only)  --  object type
  632. `boxtype'
  633.      int  --  box type
  634.      float  --  x origin
  635.      float  --  y origin
  636.      float  --  width
  637.      float  --  height
  638. `col1'
  639.      int  --  primary color
  640. `col2'
  641.      int  --  secondary color
  642. `align'
  643.      int  --  alignment
  644. `lcol'
  645.      int  --  label color
  646. `lsize'
  647.      float  --  label font size
  648. `label'
  649.      string  --  label string
  650. `lstyle'
  651.      int  --  label style
  652. `pushed'
  653.      int (read-only)  --  (see FORMS docs)
  654. `focus'
  655.      int (read-only)  --  (see FORMS docs)
  656. `belowmouse'
  657.      int (read-only)  --  (see FORMS docs)
  658. `frozen'
  659.      int (read-only)  --  (see FORMS docs)
  660. `active'
  661.      int (read-only)  --  (see FORMS docs)
  662. `input'
  663.      int (read-only)  --  (see FORMS docs)
  664. `visible'
  665.      int (read-only)  --  (see FORMS docs)
  666. `radio'
  667.      int (read-only)  --  (see FORMS docs)
  668. `automatic'
  669.      int (read-only)  --  (see FORMS docs)
  670. File: python-lib.info,  Node: FL (uppercase),  Next: flp,  Prev: fl,  Up: SGI MACHINES ONLY
  671. Standard Module `FL'
  672. ====================
  673. This module defines symbolic constants needed to use the built-in
  674. module `fl' (see above); they are equivalent to those defined in the C
  675. header file `<forms.h>' except that the name prefix `FL_' is omitted. 
  676. Read the module source for a complete list of the defined names. 
  677. Suggested use:
  678.      import fl
  679.      from FL import *
  680. File: python-lib.info,  Node: flp,  Next: panel,  Prev: FL (uppercase),  Up: SGI MACHINES ONLY
  681. Standard Module `flp'
  682. =====================
  683. This module defines functions that can read form definitions created
  684. by the `form designer' (`fdesign') program that comes with the FORMS
  685. library (see module `fl' above).
  686. For now, see the file `flp.doc' in the Python library source directory
  687. for a description.
  688. XXX A complete description should be inserted here!
  689. File: python-lib.info,  Node: panel,  Next: panelparser,  Prev: flp,  Up: SGI MACHINES ONLY
  690. Standard Module `panel'
  691. =======================
  692. *Please note:* The FORMS library, to which the `fl' module described
  693. above interfaces, is a simpler and more accessible user interface
  694. library for use with GL than the Panel Module (besides also being by a
  695. Dutch author).
  696. This module should be used instead of the built-in module `pnl' to
  697. interface with the *Panel Library*.
  698. The module is too large to document here in its entirety.  One
  699. interesting function:
  700.  -- function of module panel: defpanellist (FILENAME)
  701.      Parses a panel description file containing S-expressions written
  702.      by the *Panel Editor* that accompanies the Panel Library and
  703.      creates the described panels.  It returns a list of panel objects.
  704. *Warning:* the Python interpreter will dump core if you don't create a
  705. GL window before calling `panel.mkpanel()' or `panel.defpanellist()'.
  706. File: python-lib.info,  Node: panelparser,  Next: pnl,  Prev: panel,  Up: SGI MACHINES ONLY
  707. Standard Module `panelparser'
  708. =============================
  709. This module defines a self-contained parser for S-expressions as output
  710. by the Panel Editor (which is written in Scheme so it can't help
  711. writing S-expressions).  The relevant function is
  712. `panelparser.parse_file(FILE)' which has a file object (not a
  713. filename!) as argument and returns a list of parsed S-expressions. 
  714. Each S-expression is converted into a Python list, with atoms converted
  715. to Python strings and sub-expressions (recursively) to Python lists. 
  716. For more details, read the module file.
  717. File: python-lib.info,  Node: pnl,  Next: jpeg,  Prev: panelparser,  Up: SGI MACHINES ONLY
  718. Built-in Module `pnl'
  719. =====================
  720. This module provides access to the *Panel Library* built by NASA Ames
  721. (to get it, send e-mail to panel-request@nas.nasa.gov).  All access to
  722. it should be done through the standard module `panel', which
  723. transparantly exports most functions from `pnl' but redefines
  724. `pnl.dopanel()'.
  725. *Warning:* the Python interpreter will dump core if you don't create a
  726. GL window before calling `pnl.mkpanel()'.
  727. The module is too large to document here in its entirety.
  728. File: python-lib.info,  Node: jpeg,  Next: imgfile,  Prev: pnl,  Up: SGI MACHINES ONLY
  729. Built-in Module `jpeg'
  730. ======================
  731. The module jpeg provides access to the jpeg compressor and
  732. decompressor written by the Independent JPEG Group. JPEG is a (draft?)
  733. standard for compressing pictures.  For details on jpeg or the
  734. Indepent JPEG Group software refer to the JPEG standard or the
  735. documentation provided with the software.
  736. The jpeg module defines these functions:
  737.  -- function of module jpeg: compress (DATA, W, H, B)
  738.      Treat data as a pixmap of width w and height h, with b bytes per
  739.      pixel.  The data is in sgi gl order, so the first pixel is in the
  740.      lower-left corner. This means that lrectread return data can
  741.      immedeately be passed to compress.  Currently only 1 byte and 4
  742.      byte pixels are allowed, the former being treaded as greyscale
  743.      and the latter as RGB color.  Compress returns a string that
  744.      contains the compressed picture, in JFIF format.
  745.  -- function of module jpeg: decompress (DATA)
  746.      Data is a string containing a picture in JFIF format. It returns a
  747.      tuple `(DATA, WIDTH, HEIGHT, BYTESPERPIXEL)'.  Again, the data is
  748.      suitable to pass to lrectwrite.
  749.  -- function of module jpeg: setoption (NAME, VALUE)
  750.      Set various options.  Subsequent compress and decompress calls
  751.      will use these options.  The following options are available:
  752.     `'forcegray''
  753.           Force output to be grayscale, even if input is RGB.
  754.     `'quality''
  755.           Set the quality of the compressed image to a value between
  756.           `0' and `100' (default is `75').  Compress only.
  757.     `'optimize''
  758.           Perform huffman table optimization.  Takes longer, but
  759.           results in smaller compressed image.  Compress only.
  760.     `'smooth''
  761.           Perform inter-block smoothing on uncompressed image.  Only
  762.           useful for low-quality images.  Decompress only.
  763. Compress and uncompress raise the error jpeg.error in case of errors.
  764. File: python-lib.info,  Node: imgfile,  Next: imageop,  Prev: jpeg,  Up: SGI MACHINES ONLY
  765. Built-in module `imgfile'
  766. =========================
  767. The imgfile module allows python programs to access SGI imglib image
  768. files (also known as `.rgb' files).  The module is far from complete,
  769. but is provided anyway since the functionality that there is is enough
  770. in some cases.  Currently, colormap files are not supported.
  771. The module defines the following variables and functions:
  772.  -- exception of module imgfile: error
  773.      This exception is raised on all errors, such as unsupported file
  774.      type, etc.
  775.  -- function of module imgfile: getsizes (FILE)
  776.      This function returns a tuple `(X, Y, Z)' where X and Y are the
  777.      size of the image in pixels and Z is the number of bytes per
  778.      pixel. Only 3 byte RGB pixels and 1 byte greyscale pixels are
  779.      currently supported.
  780.  -- function of module imgfile: read (FILE)
  781.      This function reads and decodes the image on the specified file,
  782.      and returns it as a python string. The string has either 1 byte
  783.      greyscale pixels or 4 byte RGBA pixels. The bottom left pixel is
  784.      the first in the string. This format is suitable to pass to
  785.      `gl.lrectwrite', for instance.
  786.  -- function of module imgfile: readscaled (FILE, X, Y, FILTER, BLUR)
  787.      This function is identical to read but it returns an image that is
  788.      scaled to the given X and Y sizes. If the FILTER and BLUR
  789.      parameters are omitted scaling is done by simply dropping or
  790.      duplicating pixels, so the result will be less than perfect,
  791.      especially for computer-generated images.
  792.      Alternatively, you can specify a filter to use to smoothen the
  793.      image after scaling. The filter forms supported are `'impulse'',
  794.      `'box'', `'triangle'', `'quadratic'' and `'gaussian''. If a
  795.      filter is specified BLUR is an optional parameter specifying the
  796.      blurriness of the filter. It defaults to `1.0'.
  797.      Readscaled makes no attempt to keep the aspect ratio correct, so
  798.      that is the users' responsibility.
  799.  -- function of module imgfile: write (FILE, DATA, X, Y, Z)
  800.      This function writes the RGB or greyscale data in DATA to image
  801.      file FILE. X and Y give the size of the image, Z is 1 for 1 byte
  802.      greyscale images or 3 for RGB images (which are stored as 4 byte
  803.      values of which only the lower three bytes are used).  These are
  804.      the formats returned by `gl.lrectread'.
  805. File: python-lib.info,  Node: imageop,  Prev: imgfile,  Up: SGI MACHINES ONLY
  806. Built-in module `imageop'
  807. =========================
  808. The imageop module contains some useful operations on images.  It
  809. operates on images consisting of 8 or 32 bit pixels stored in python
  810. strings. This is the same format as used by `gl.lrectwrite' and the
  811. `imgfile' module.
  812. The module defines the following variables and functions:
  813.  -- exception of module imageop: error
  814.      This exception is raised on all errors, such as unknown number of
  815.      bits per pixel, etc.
  816.  -- function of module imageop: crop (IMAGE, PSIZE, WIDTH, HEIGHT, X0,
  817.           Y0, X1, Y1)
  818.      This function takes the image in `image', which should by `width'
  819.      by `height' in size and consist of pixels of `psize' bytes, and
  820.      returns the selected part of that image. `X0', `y0', `x1' and
  821.      `y1' are like the `lrectread' parameters, i.e. the boundary is
  822.      included in the new image.  The new boundaries need not be inside
  823.      the picture. Pixels that fall outside the old image will have
  824.      their value set to zero.  If `x0' is bigger than `x1' the new
  825.      image is mirrored. The same holds for the y coordinates.
  826.  -- function of module imageop: scale (IMAGE, PSIZE, WIDTH, HEIGHT,
  827.           NEWWIDTH, NEWHEIGHT)
  828.      This function returns a `image' scaled to size `newwidth' by
  829.      `newheight'. No interpolation is done, scaling is done by
  830.      simple-minded pixel duplication or removal. Therefore,
  831.      computer-generated images or dithered images will not look nice
  832.      after scaling.
  833.  -- function of module imageop: tovideo (IMAGE, PSIZE, WIDTH, HEIGHT)
  834.      This function runs a vertical low-pass filter over an image. It
  835.      does so by computing each destination pixel as the average of two
  836.      vertically-aligned source pixels. The main use of this routine is
  837.      to forestall excessive flicker if the image is displayed on a
  838.      video device that uses interlacing, hence the name.
  839.  -- function of module imageop: grey2mono (IMAGE, WIDTH, HEIGHT,
  840.           THRESHOLD)
  841.      This function converts a 8-bit deep greyscale image to a 1-bit
  842.      deep image by tresholding all the pixels. The resulting image is
  843.      tightly packed and is probably only useful as an argument to
  844.      `mono2grey'.
  845.  -- function of module imageop: dither2mono (IMAGE, WIDTH, HEIGHT)
  846.      This function also converts an 8-bit greyscale image to a 1-bit
  847.      monochrome image but it uses a (simple-minded) dithering
  848.      algorithm.
  849.  -- function of module imageop: mono2grey (IMAGE, WIDTH, HEIGHT, P0,
  850.           P1)
  851.      This function converts a 1-bit monochrome image to an 8 bit
  852.      greyscale or color image. All pixels that are zero-valued on
  853.      input get value `p0' on output and all one-value input pixels get
  854.      value `p1' on output. To convert a monochrome black-and-white
  855.      image to greyscale pass the values `0' and `255' respectively.
  856.  -- function of module imageop: grey2grey4 (IMAGE, WIDTH, HEIGHT)
  857.      Convert an 8-bit greyscale image to a 4-bit greyscale image
  858.      without dithering.
  859.  -- function of module imageop: grey2grey2 (IMAGE, WIDTH, HEIGHT)
  860.      Convert an 8-bit greyscale image to a 2-bit greyscale image
  861.      without dithering.
  862.  -- function of module imageop: dither2grey2 (IMAGE, WIDTH, HEIGHT)
  863.      Convert an 8-bit greyscale image to a 2-bit greyscale image with
  864.      dithering. As for `dither2mono', the dithering algorithm is
  865.      currently very simple.
  866.  -- function of module imageop: grey42grey (IMAGE, WIDTH, HEIGHT)
  867.      Convert a 4-bit greyscale image to an 8-bit greyscale image.
  868.  -- function of module imageop: grey22grey (IMAGE, WIDTH, HEIGHT)
  869.      Convert a 2-bit greyscale image to an 8-bit greyscale image.
  870. File: python-lib.info,  Node: SUN SPARC MACHINES ONLY,  Next: AUDIO TOOLS,  Prev: SGI MACHINES ONLY,  Up: Top
  871. SUN SPARC MACHINES ONLY
  872. ***********************
  873. * Menu:
  874. * sunaudiodev::                 Built-in module `sunaudiodev'
  875. File: python-lib.info,  Node: sunaudiodev,  Up: SUN SPARC MACHINES ONLY
  876. Built-in module `sunaudiodev'
  877. =============================
  878. This module allows you to access the sun audio interface. The sun
  879. audio hardware is capable of recording and playing back audio data in
  880. U-LAW format with a sample rate of 8K per second. A full description
  881. can be gotten with `man audio'.
  882. The module defines the following variables and functions:
  883.  -- exception of module sunaudiodev: error
  884.      This exception is raised on all errors. The argument is a string
  885.      describing what went wrong.
  886.  -- function of module sunaudiodev: open (MODE)
  887.      This function opens the audio device and returns a sun audio
  888.      device object. This object can then be used to do I/O on. The
  889.      MODE parameter is one of `'r'' for record-only access, `'w'' for
  890.      play-only access, `'rw'' for both and `'control'' for access to
  891.      the control device. Since only one process is allowed to have the
  892.      recorder or player open at the same time it is a good idea to
  893.      open the device only for the activity needed. See the audio
  894.      manpage for details.
  895. * Menu:
  896. * Audio device object methods::  Audio device object methods
  897. File: python-lib.info,  Node: Audio device object methods,  Up: sunaudiodev
  898. Audio device object methods
  899. ---------------------------
  900. The audio device objects are returned by `open' define the following
  901. methods (except `control' objects which only provide getinfo, setinfo
  902. and drain):
  903.  -- Method on audio device: close ()
  904.      This method explicitly closes the device. It is useful in
  905.      situations where deleting the object does not immediately close
  906.      it since there are other references to it. A closed device should
  907.      not be used again.
  908.  -- Method on audio device: drain ()
  909.      This method waits until all pending output is processed and then
  910.      returns.  Calling this method is often not necessary: destroying
  911.      the object will automatically close the audio device and this
  912.      will do an implicit drain.
  913.  -- Method on audio device: flush ()
  914.      This method discards all pending output. It can be used avoid the
  915.      slow response to a user's stop request (due to buffering of up to
  916.      one second of sound).
  917.  -- Method on audio device: getinfo ()
  918.      This method retrieves status information like input and output
  919.      volume, etc. and returns it in the form of an audio status
  920.      object. This object has no methods but it contains a number of
  921.      attributes describing the current device status. The names and
  922.      meanings of the attributes are described in
  923.      `/usr/include/sun/audioio.h' and in the audio man page. Member
  924.      names are slightly different from their C counterparts: a status
  925.      object is only a single structure. Members of the `play'
  926.      substructure have `o_' prepended to their name and members of the
  927.      `record' structure have `i_'. So, the C member `play.sample_rate'
  928.      is accessed as `o_sample_rate', `record.gain' as `i_gain' and
  929.      `monitor_gain' plainly as `monitor_gain'.
  930.  -- Method on audio device: ibufcount ()
  931.      This method returns the number of samples that are buffered on the
  932.      recording side, i.e.  the program will not block on a `read' call
  933.      of so many samples.
  934.  -- Method on audio device: obufcount ()
  935.      This method returns the number of samples buffered on the playback
  936.      side. Unfortunately, this number cannot be used to determine a
  937.      number of samples that can be written without blocking since the
  938.      kernel output queue length seems to be variable.
  939.  -- Method on audio device: read (SIZE)
  940.      This method reads SIZE samples from the audio input and returns
  941.      them as a python string. The function blocks until enough data is
  942.      available.
  943.  -- Method on audio device: setinfo (STATUS)
  944.      This method sets the audio device status parameters. The STATUS
  945.      parameter is an device status object as returned by `getinfo' and
  946.      possibly modified by the program.
  947.  -- Method on audio device: write (SAMPLES)
  948.      Write is passed a python string containing audio samples to be
  949.      played.  If there is enough buffer space free it will immedeately
  950.      return, otherwise it will block.
  951. There is a companion module, `SUNAUDIODEV', which defines useful
  952. symbolic constants like `MIN_GAIN', `MAX_GAIN', `SPEAKER', etc. The
  953. names of the constants are the same names as used in the C include file
  954. `<sun/audioio.h>', with the leading string `AUDIO_' stripped.
  955. Useability of the control device is limited at the moment, since there
  956. is no way to use the 'wait for something to happen' feature the device
  957. provides. This is because that feature makes heavy use of signals, and
  958. these do not map too well onto Python.
  959. File: python-lib.info,  Node: AUDIO TOOLS,  Next: CRYPTOGRAPHIC EXTENSIONS,  Prev: SUN SPARC MACHINES ONLY,  Up: Top
  960. AUDIO TOOLS
  961. ***********
  962. * Menu:
  963. * audioop::                     Built-in module `audioop'
  964.